/*******************************************************************************
 * Copyright  2015 rzorzorzo@users.sf.net
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *******************************************************************************/
package org.rzo.netty.ahessian.rpc.server;

import java.util.Date;

import org.rzo.netty.ahessian.session.Session;

/**
 * Continuation offers similar functionality as <a
 * href="http://docs.codehaus.org/display/JETTY/Continuations">Jetty
 * Continuations</a> <br>
 * A continuation is a mechanism by which an RPC request can be suspended and
 * restarted after a timeout or an asynchronous event has occured. <br>
 * Typical usage within a service: <br>
 * The service interface exposed to the client: <br>
 * 
 * <pre>
 * public TableData getTableData(Filter filter)
 * </pre>
 * 
 * <br>
 * The service object implementation: <br>
 * 
 * <pre>
 * public TableData getTableData(Continuation continuation, Filter filter)
 * {
 *      if (requestOk(filter))
 *      	// add client to client list
 * 			addClient(continuation, filter, context);
 * 	else // or send an error
 * 	    // continuation.fault(new Exception...());
 * }
 * 
 * void onTableDataChange()
 * {
 *   // when table data changes send the new data to all attached clients
 *   for (client : clients)
 *   {
 *     TableData newData = ...
 *     client.getContinuation().send(newData)
 *   }
 * }
 * 
 * void onTableClosed()
 * {
 *   // on shutdown inform all clients that the invocation is completed and no further
 *   // data will be sent.
 *   for (client : clients)
 *   {
 *     client.getContinuation().completed(null);
 *   }
 *   clients.reset();
 * }
 * 
 * </pre>
 * 
 */
public interface Continuation
{

	/**
	 * Send an invocation reply to the client
	 * 
	 * @param result
	 *            the result
	 */
	public void send(Object result);

	/**
	 * Send the last reply to the client and inform that this is the last reply
	 * for the invocation request
	 * 
	 * @param result
	 *            the result
	 */
	public void complete(Object result);

	/**
	 * Send an error to the client and inform that this is the last reply for
	 * the invocation request
	 * 
	 * @param result
	 *            the result
	 */
	public void fault(Throwable result);

	/**
	 * If the client has given us a time out for the invocation calling send,
	 * complete or fault after the given point in time will result in an
	 * exception
	 * 
	 * @return the tTL
	 */
	public Date getTTL();

	public Session getSession();
}
